home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / DESQVIEW / QTECH527.ARJ / XDI.TEC < prev    next >
Text File  |  1991-03-12  |  9KB  |  169 lines
  1. ID:XD XDI Specification for DESQview
  2. Quarterdeck Technical Note #182
  3. by Daniel Travison
  4.  
  5. Q: How can my device driver/TSR work better with DESQview?
  6.  
  7. DESQview's External Device Interface
  8.  
  9. DESQview version 2.26 (and above), can issue informative messages
  10. to third party software in order for that software to monitor
  11. certain DESQview operations such as starting a task or swapping
  12. out a process.  These messages can be useful for determining when
  13. to allocate/deallocate resources (e.g., memory) on a process by
  14. process basis, communicating with tasks running within DESQview,
  15. rescheduling tasks, tracking DESQview's task switching, etc.
  16.  
  17. DESQview provides this information through the External Device
  18. Interface (XDI) - Quarterdeck's specification for communicating
  19. with external drivers.
  20.  
  21. An XDI driver may be implemented either as a DOS device driver
  22. (loaded by CONFIG.SYS), a Terminate and Stay Resident program
  23. (TSR) loaded before or after DESQview, or as a DESQview shared
  24. program (shared among several processes).  For the rest of this
  25. documentation, the term 'driver' will normally refer to a program
  26. that uses the XDI irrespective of its method of implementation
  27. (device driver, TSR or shared program).  Also, any number of XDI
  28. drivers can be loaded.  When DESQview starts, it simply attaches
  29. itself to the XDI chain and starts sending XDI messages to to
  30. previously loaded XDI drivers.
  31.  
  32. Within the XDI, there are 15 subfunctions (messages).  Fourteen
  33. of these messages inform the driver what action DESQview has just
  34. performed or is about to perform.  Your driver can choose to
  35. ignore the message and pass it on to the next driver in the
  36. chain, perform/schedule work based on the message, or save
  37. information for later use (e.g., the current mapping context). 
  38.  
  39.         XDI_CHECK_PRESENCE      Check for XDI driver presence     
  40.         XDI_RESERVED_SUBFUNC    XDI driver custom subfunction     
  41.         XDD_START_DV            DV system initialization complete 
  42.         XDI_END_DV              DV system termination             
  43.         XDI_START_PROC          DV process creation
  44.         XDI_END_PROC            DV process termination            
  45.         XDI_START_TASK          Task creation
  46.         XDI_END_TASK            Task termination
  47.         XDI_SAVE_STATE          Task state save
  48.         XDI_RESTORE_STATE       Task state restore
  49.         XDI_KEYBOARD            Change of keyboard focus          
  50.         XDI_PROCESS_DVP         Processing of DVP file complete   
  51.         XDI_SWAPPING_OUT        Swap out of DV process            
  52.         XDI_SWAPPED_IN          Swap in of DV process             
  53.         XDI_FAILED_DVP          DV process creation failure
  54.  
  55. An XDI driver can schedule second level handlers to make API
  56. calls, collect data, transfer data, dispatch tasks, perform
  57. initialization/termination when DESQview is started and quit.
  58.  
  59. The fifteenth subfunction, XDI_RESERVED_SUBFUNC provides a method
  60. for applications to communicate with your driver without needing
  61. to grab an additional interrupt vector.  Additionally, this
  62. interface does not require DESQview to be loaded.  In other
  63. words, if DESQview is not loaded, the application and XDI driver
  64. will still be able to communicate.
  65.  
  66. Q: When would I want to use the XDI specification?
  67.  
  68. If your driver needs to write into an application's address space
  69. then you need to ensure that the address is valid when you
  70. perform the write.  (e.g., The DOS SETDTA call requires the
  71. caller provide a pointer to a buffer that will be filled in at a
  72. later time.  A communications handler might use a similar
  73. interface but perform the update at interrupt time.) With
  74. DESQview, this buffer may get mapped in and out to accomodate
  75. running multiple programs.  If your driver attempts to write into
  76. this buffer when DESQview has mapped some other application into
  77. it (e.g., at interrupt time) then you will be corrupting the
  78. unknown application.  The XDI allows your driver to determine
  79. when the write operation is safe or specifically request that
  80. DESQview map the application in to allow safe access to the
  81. application's address space.
  82.  
  83. Another example is the use of Multiplex boards.  Multiplex boards
  84. have two important features: One, they provide access to multiple
  85. external devices (e.g., modems) using a single IRQ and two, they
  86. provide a software interface for applications.  The software
  87. interface removes the need for the application to manage the
  88. hardware directly.  In the case of a multiplex board providing
  89. additional serial ports, the user will often want to run more
  90. than one program at a time to take advantage extra serial ports. 
  91. (e.g., A number of BBS systems provide the option for running
  92. multiple copies at once and also support drivers for multiplex
  93. boards.) The programmer writing the driver will need to
  94. accomodate simultaneous access to the driver as well as provide a
  95. reliable software interface.
  96.  
  97. Other issues addressed by the XDI:
  98.  
  99.   1) Allocation of a software interrupt to allow the application
  100. to communicate with the driver.  With more and more device
  101. drivers and TSR's available, it is important to prevent possible
  102. conflicts with other software.  The XDI specification uses the
  103. multiplex interrupt (INT 2Fh) as a basis for sharing a single
  104. interrupt using a well defined interface.  Once the application
  105. has 'logged' itself with the driver (XDI_RESERVED_SUBFUNC), the
  106. driver might provide an ID for future use or simply manage it
  107. internally based on which process DESQview has mapped in when the
  108. software interrupt is called.  This portion of the interface
  109. functions in the same manner whether DESQview is loaded or not. 
  110. When DESQview is not present, the driver does not need to be
  111. concerned with the mapping context.
  112.  
  113.   2) Allocation of memory/application that needs to be accessible
  114. at any given time.  This might be a buffer for incoming data. 
  115. Normally, the driver would need to allocate all of its memory
  116. needs during its initialization code.  DESQview allows an XDI
  117. driver to allocate COMMON memory (memory that does not get mapped
  118. out) during an XDI call.  This allows the driver to allocate only
  119. the memory necessary when a new application starts.  It DESQview
  120. is not present, the application would allocate a buffer out of
  121. its own data space.  A check for DESQview would be all that is
  122. necessary for the application to determine whether it needs to
  123. allocate a buffer or allow the driver to allocate it from COMMON
  124. memory.
  125.  
  126.   3) Preventing reentrancy during non-reentrant sections of code. 
  127. In a perfect world, all of your driver's code would be reentrant. 
  128. Since this may not be practical without unreasonble code or CPU
  129. overhead, the XDI driver can temporarily suspend multitasking to
  130. perform its critical work.  This does not mean that the XDI
  131. allows you to write non-reentrant handlers but it can solve some
  132. sticky issues that arise when you need to support simultaneous
  133. access.
  134.  
  135.   4) The application can not keep up with the data rate.  There
  136. will be times when the application can not empty the driver's
  137. buffer faster than the driver can fill it.  The user may have
  138. started up a few extra applications and the CPU is too slow to
  139. give everyone enough time.  The XDI driver could consider some
  140. percentage of the buffer as a threshold.  When this threshold is
  141. reached the driver can temporarily override DESQview's dispatcher
  142. and force the application's 'buffer management' routine to
  143. execute at the next context switch.
  144.  
  145.   5) The driver needs to know when the application exits to allow
  146. proper cleanup.  Normally, the application itself would call the
  147. driver to initiate cleanup.  Occasionally this will not occur
  148. (e.g., the user shut down the application via DESQview's Close
  149. Window menu selection).  DESQview notifies the XDI driver when a
  150. process ends to allow the driver to determine if it needs to
  151. perform any cleanup for the process.
  152.  
  153. There are other areas where an XDI driver would be of use;
  154. resource tracking on a process by process basis, modifying the
  155. .DVP when each process starts, allocating additional system
  156. memory for the process at startup, tracking CPU usage, or even
  157. displacing DESQview's dispatcher.
  158.  
  159. Q: How do I find out more about the XDI?
  160.  
  161. DESQview's XDI is fully documented in Quarterdeck's API Reference
  162. Manual (versions 1.20 and later).  Included is a sample XDI
  163. driver (POKEXDI.ASM) that can be used as a template for designing
  164. your own.  Contact Quarterdeck for information on obtaining a
  165. copy of our API Reference Manual or upgrading and older API
  166. Reference Manual.
  167.  
  168.         Copyright (C) 1991 by Quarterdeck Office Systems
  169.                * * * E N D  O F  F I L E * * *